home *** CD-ROM | disk | FTP | other *** search
/ Hottest 6 / Hottest 6 (1996)(PDSoft)[!].iso / software / fredfish / 1099.lha / Programs / SerLog / serlog.doc < prev    next >
Text File  |  1995-03-19  |  14KB  |  316 lines
  1.  
  2.  
  3.  
  4.                               SERLOG.DEVICE
  5.  
  6.  
  7. Preface
  8. ~~~~~~~
  9.   Space - the final frontier! These are the vo... oh, sorry :-)
  10.   "serlog.device" is a special purpose debugging tool which allows you to
  11.   monitor serial-IO.
  12.   I wrote this when trying to track down some problems with my FAX-Software
  13.   and was ask to make it available to other people.
  14.  
  15.  
  16. Legal stuff
  17. ~~~~~~~~~~~
  18.   serlog.device is Copyright (c) by the author Stefan Pröls.
  19.   It is released as FREEWARE meaning that you may distribute and use it in
  20.   any form without limitations.
  21.   There is absolutely no warranty on any part of this package.
  22.   Use it on your own risk.
  23.  
  24.  
  25. Technical Overview
  26. ~~~~~~~~~~~~~~~~~~
  27.   serlog.device passes all IOExtSer requests to a "real" serial.device
  28.   and writes the results to a file.
  29.   You may configure the amount of information to be stored in the log.
  30.   The log-file created by serlog.device contains a binary dump which can
  31.   be formatted (i.e. transferred into a readable version) using the supplied
  32.   formatter.
  33.  
  34.   Note that serlog.device uses *significant* overhead over the underlying
  35.   serial.device, resulting in very low baud-rates.
  36.  
  37.   OS 2.0 or greater is required.
  38.  
  39.  
  40. Installation
  41. ~~~~~~~~~~~~
  42.   Just copy "serlog.device" to "DEVS:" and the supplied programs "slprefs"
  43.   and "fmtlog" to any place you want.
  44.   If you have a CPU >= 68020 use the binaries from the bin020 directory,
  45.   otherwise use the ones from bin000.
  46.  
  47.   If you have problems with the speed try to reduce mulitasking while
  48.   serlog.device is in use and try to hold most things in 32 Bit FAST
  49.   memory. E.g. "CPU FASTROM" will result in a significant speed-up on
  50.   68030 CPUs using 16-Bit ROMS (e.g. A2k-30).
  51.  
  52.   When using high-speed connections hardware-overflow errors may occur.
  53.   However, sensible protocols should handle them.
  54.   Take this as general information, not as warning! Software should never
  55.   have problems with the device, *very* sensitive hardware *may* however.
  56.   Also note that version 1.4 comes up with a significant speed-up and
  57.   some options to get along even with hardware depending on sensitive
  58.   timing.
  59.  
  60.  
  61. Usage
  62. ~~~~~
  63.   Tell the software you want to debug to use "serlog.device" unit 0 instead
  64.   of "serial.device".
  65.  
  66.   Before you start the program you should tell the device what to monitor.
  67.   "slprefs" is used for that.
  68.  
  69.   "slprefs" is a shell-driven -- sorry ;-) -- preferences utility for the
  70.   serlog.device. Basically it allows you to turn on and off monitoring of
  71.   certain commands like "CMD_READ". To do so specify the appropriate commands
  72.   and append "ADD" or "SUB" to the command line. You may get a list of possible
  73.   commands by the includes or by typing "slprefs ?".
  74.   There are some more options:
  75.  
  76.     DEVICE      -- The underlying device used to execute commands.
  77.                    E.g. "serial.device".
  78.  
  79.     UNIT        -- The unit of the underlying device.
  80.                    DO NOT MIX THIS UP with the unit of "serlog.device"!
  81.                    serlog.device supports *ONLY* unit *0*.
  82.                    If you have some kind of multi-IO board you may for example
  83.                    specify "DEVICE=multiio.device UNIT=2" which means that
  84.                    "serlog.device" when opened for unit *0* will use unit 2
  85.                    of "multiio.device".
  86.  
  87.     PRIORITY    -- Priority of serlog's server task. By default this equals 0.
  88.                    This causes trouble with some special applications. (E.g.
  89.                    MultiFax usually doesn't work with TKR's SpeedStar if
  90.                    priority is 0). This is NOT a bug in serlog but a timing
  91.                    problem between the software and the connected device.
  92.                    Try PRIORITY=2 if you're having problems.
  93.  
  94.     FILENAME    -- Captains log. This is the name of the file the protocol
  95.                    will be written to.
  96.  
  97.                    YOU SHOULD NEVER
  98.                    use a FILENAME in RAM: It might not actually cause trouble,
  99.                    but it is really, well, silly. If you have enough memory
  100.                    to store the file on a RAM disk you should store it on a
  101.                    harddisk and use a big BUFFERSIZE to buffer the *complete*
  102.                    file during IO operations. There is no need to waste
  103.                    expensive CPU time for filesystems, etc.
  104.  
  105.                    YOU MUST NEVER
  106.                    use a relative path. Always provide a full path. Again,
  107.                    violance against this recommendation might not actually
  108.                    cause trouble, but if you wish to find the logfile you
  109.                    should keep it in mind, because you don't know the
  110.                    working directory for the server task which opens the
  111.                    file...
  112.                    A good FILENAME is something like "SYS:t/serlog.log",
  113.                    which is the default.
  114.  
  115.     BUFFERSIZE  -- Size of buffer used for writing to FILENAME.
  116.                    Since version 1.4 the device no longer uses DOS' buffered
  117.                    IO functions but a much more efficient special-purpose
  118.                    buffering technique. The BUFFERSIZE option is used to
  119.                    set the size of the buffer in byte.
  120.                    Actually the device will use *about* BUFFERSIZE byte,
  121.                    i.e. it will adjust BUFFERSIZE to fit its needs.
  122.  
  123.                    IMPORTANT:
  124.                    This options can by very useful and very dangerous!
  125.  
  126.                    1. A bigger buffer generally speeds up the device, thus
  127.                       if you have timing problems with your hardware (e.g.
  128.                       the modem) you may want to increase the BUFFERSIZE.
  129.  
  130.                    2. Sooner or later the buffer needs to be written to disk.
  131.                       This will block IO operations, not to mention problems
  132.                       with harddisks which lock interrupts.
  133.  
  134.                    SO, HOW TO USE IT?
  135.                    If you have enough memory use a real big buffer! Say 2 MB
  136.                    or even more. This will allow to buffer a *COMPLETE*
  137.                    session! The buffer will not be written to disk until
  138.                    the device is closed. You may want to run a test-session
  139.                    first to figure out how big the log-file becomes and then
  140.                    choose BUFFERSIZE a bit bigger than that.
  141.                    If you have not much memory use something between 256 byte
  142.                    and some kB, depending on the application you're debugging.
  143.  
  144.                    By default serlog will use 256 byte, which is the
  145.                    (internal) minimum and about the same DOS used to use for
  146.                    serlog version <= 1.3.
  147.  
  148.     SHOW        -- Shows the current settings. They are always shown but when
  149.                    this option is specified they will *only* be shown, i.e.
  150.                    changes will have no effect.
  151.  
  152.     CMD_*,
  153.     SDCMD_*     -- Commands to (or not to) monitor.
  154.  
  155.     ALL         -- Same as all (SD)CMD_*s.
  156.  
  157.     ADD         -- Turn on monitoring (SD)CMD_*s
  158.  
  159.     SUB         -- Turn off monitoring (SD)CMD_*s
  160.  
  161.     DEFAULTS    -- Reset all preferences to their default values.
  162.  
  163.     (NO)APPEND  -- When APPEND is on, the log-file will not be deleted when
  164.                    OpenDevice() is called but all new data will be appended.
  165.                    Useful in case you're using "OwnDevUnit.library",
  166.                    for example.
  167.  
  168.     (NO)TIME    -- When TIME is on, serlog will supply ever entry in the
  169.                    log-file with the time the IORequest has been sent and
  170.                    the duration of it's completion.
  171.  
  172.                    NOTE:
  173.                    "TIME" causes serlog using more overhead. E.g it will
  174.                    have to transfer more memory. Therefore it is strongly
  175.                    recommended to
  176.                    a) specify a BUFFERSIZE large enough to buffer a
  177.                       complete session,
  178.                    b) set PRIORITY to, say, 2,
  179.                    c) not to use "TIME" if you don't need it.
  180.  
  181.                    Also note:
  182.                    Due to multitasking TIME is not able to provide exact
  183.                    values, actually they can be quite inaccurate. The
  184.                    time when an IORequest has been sent ist quite exact,
  185.                    though.
  186.  
  187.                    @@@ further explanation for public release required
  188.  
  189.   Note that any changes to the preferences will not have effect until the
  190.   device is restarted, i.e. when OpenDevice() (with exclusive access) is
  191.   called the next time.
  192.  
  193.  
  194.   The log-file created by serlog.device contains a binary dump of information
  195.   about processed IOExtSer requests. To create a readable output you use the
  196.   "fmtlog" utility.
  197.  
  198.   If you do not specify a name for the log-file "fmtlog" will use the one set
  199.   with slprefs. "fmtlog" knows a few more or less useful options:
  200.  
  201.     GURULAYOUT  -- Do not create a "nice" output but a very compact one.
  202.                    Normal human beings are likely to get completely mad
  203.                    when reading that. However, if you're a guru and you
  204.                    want to format a very large file which would produce
  205.                    an even larger output you may try this.
  206.  
  207.     BRIEF       -- Do not extract all available information but only a
  208.                    brief overview on what happened. Basically there will
  209.                    be no data for CMD_READ and CMD_WRITE.
  210.  
  211.     CDUMP       -- When dumping binary data use "\x??" notation for writing
  212.                    non-ASCII characters. Otherwise all non-printable
  213.                    characters will shown by ".".
  214.                    When CDUMP is specified some further 'C' like notations
  215.                    will be used, e.g. '\n' for NL or '\\' for "\". Quotes
  216.                    however will not be affected.
  217.                    This option has no effect when BRIEF is on.
  218.  
  219.     HEXDUMP     -- When dumping data (e.g. CMD_READ, CMD_WRITE) print it
  220.                    similar as "type <foobar> hex".
  221.                    This option has no effect when BRIEF is on.
  222.                    HEXDUMP and CDUMP cannot be used at the same time.
  223.  
  224.  
  225.  
  226. History
  227. ~~~~~~~
  228.   1.0   - works for me and only for me...
  229.   1.1   - temporary version
  230.   1.2   - complete rework, first public release
  231.           This is a major update - but as this isn't a SASG product this
  232.           doesn't matter.
  233.   1.3   - fixed a problem which made the preferences utility unusable
  234.           due to a bug in AmigaOS versions prior V39.
  235.           Nothing else changed.
  236.           (First reported by Darryl Mcginnis)
  237.   1.4   - added support for shared access
  238.           added configurable PRIORITY of server task
  239.           speed-up by own memory-management functions
  240.           speed-up by own buffering functions
  241.           [bumped revision before public version was finished]
  242.   1.5   - added HEXDUMP option (Suggested by Richard Karlsson)
  243.           added TIME option (Suggested by René Hexel)
  244.   1.6   - minor internal changes, recompiled with SAS/C 6.55
  245.  
  246.  
  247.  
  248. TODO
  249. ~~~~
  250.   - MUI based GUI for slprefs
  251.     including standard SAVE USE CANCEL buttons which behave equal under
  252.     OSV37 and OSV39+
  253.   - finish a public release before starting a new beta, does anyone know
  254.     a ftp-server for days with more than 24 hours :-(
  255.  
  256.  
  257.  
  258. KNOWN PROBLEMS
  259. ~~~~~~~~~~~~~~
  260.   No, NOT bugs. I won't document bugs but fix them :)
  261.  
  262.   * Some applications depend on very sensitive timing. serlog.device *DOES*
  263.     use a significant overhead and therefore *IS* slow. Without a major
  264.     loss of compatibility (serlog claims to be very, say 100%, compatible)
  265.     there is not much I can do about it :(
  266.     For example, every (Send|Do|Begin)IO requires multible task-switches.
  267.  
  268.     In case you're running into trouble with the speed try to specify a
  269.     higher priority for the server process, BUT NOT TO HIGH!!! (You need
  270.     blanance not force.)
  271.     In most cases PRIORITY=2 should work well. You may want to use this
  272.     by default.
  273.  
  274.   * Q: Although serlog seems to work well, my logfile is always empty.
  275.        What's going on?
  276.     A: You're probably using OwnDevUnit.library or for some other reason
  277.        serlog.device is <closed, opened again, closed again> before the
  278.        program you want to debug exits.
  279.        Whenever serlog.device is opened the first time (i.e. the open
  280.        counter switches from 0 to 1) the logfile is opened and probably
  281.        deleted.
  282.        To prevent this from happening just turn on "APPEND" using slprefs.
  283.  
  284.   * Q: fmtlog always tells me "LOGFILE contains garbage".
  285.     A: You've probably rebooted your computer while serlog.device was
  286.        sill in use. So data buffered by serlog.device has not been written
  287.        to disk yet. Now fmtlog would tell you "unexpected EOF". Guess what
  288.        happens if you're starting serlog.device again in APPEND mode...
  289.        To get out of this you must delete the logfile before you're opening
  290.        serlog again after an abnormal termination (e.g. reboot).
  291.  
  292.  
  293. Target for flames
  294. ~~~~~~~~~~~~~~~~~
  295.   Ahm, flames? Hey, read the legal stuff above ;-) However, comments are
  296.   welcome. If you have any suggestions or if you think serlog.device is
  297.   THE tool you've been searching for for years and want to send me some
  298.   new Amigas or SUNs, feel free to contact me:
  299.  
  300.       Internet: serlog@p13.die-box.in-passau.de
  301.                 proels@fmi.uni-passau.de
  302.       Fidonet:  Stefan Proels,2:2494/22.13
  303.  
  304.       Snailmail (ever heard about that?):
  305.  
  306.           Stefan Pröls
  307.           Rudolf-Guby-Str. 1
  308.           94032 Passau
  309.           Germany
  310.  
  311.           Earth
  312.  
  313.  
  314.       email is preferred.
  315.  
  316.